<HTML>
<HEAD>
<TITLE>ncftpls(1) manual page</TITLE>
</HEAD>
<BODY bgcolor=white>

<H2>Name</H2>
<blockquote>
  <b>
ncftpls</b> - Internet file transfer program for scripts
</blockquote>
<H2>Synopsis</H2>
<blockquote>
<P>
<B>ncftpls</B>
[<I>options</I>]<I></I> <I>ftp://url.style/host/path/name/</I>  
</blockquote>

<center>
<p>
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick">
<input type="hidden" name="hosted_button_id" value="5JS76LUNSD3HU">
<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
<img alt="" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
</form>
</center>

<H2>Options</H2>
 Command line flags:
<blockquote>
<DL>

<DT><B>-m</B></DT>
<DD>Use a machine readable list format, if the server supports it.
This requires that the server software support the <TT>MLSD</TT>
extensions, and many implementations do not support these features.</DD>

<DT><B>-1</B></DT>
<DD>Most basic format, one item per line. </DD>

<DT><B>-l</B> </DT>
<DD>Long list format. </DD>

<DT><B>-C</B></DT>
<DD>Columnized list format.  This is the default list format. </DD>

<DT><B>-R</B> </DT>
<DD>Recurse all subdirectories while listing.</DD>

<DT><B>-a</B> </DT>
<DD>Show all files, if the server allows it (as in <TT>/bin/ls -a</TT>).</DD>

<DT><B>-i </B><I>XX</I></DT>
<DD>Filter the listing (if the server supports it) with the wildcard <I>XX</I>.</DD>

<DT><B>-x -</B><I>XX</I></DT>
<DD>List command flags to use on the remote server.</DD>

<DT><B>-u </B><I>XX</I> </DT>
<DD>Use username <I>XX</I> instead of anonymous.
</DD>

<DT><B>-p </B><I>XX</I> </DT>
<DD>Use password <I>XX</I> with the username. </DD>

<DT><B>-P </B><I>XX</I> </DT>
<DD>Use port number <I>XX</I> instead
of the default FTP service port (21). </DD>

<DT><B>-d </B><I>XX</I> </DT>
<DD>Use the file <I>XX</I> for debug logging.
</DD>

<DT><B>-t </B><I>XX</I> </DT>
<DD>Timeout after <I>XX</I> seconds. </DD>

<DT><B>-E</B> </DT>
<DD>Use regular (PORT) data connections. </DD>

<DT><B>-F</B> </DT>
<DD>Use passive (PASV) data connections.&nbsp; The default is to use passive, but to fallback to
  regular if the passive connection fails or times out. </DD>

<DT><B>-r </B><I>XX</I>
</DT>
<DD>Redial a maximum of  <I>XX</I> times until connected to the remote FTP server.
 </DD>
</DL>

<DT><B>-W </B><I>XX</I> </DT>
<DD>Send raw FTP command <I>XX</I> after logging in.</DD>

<DT><B>-X </B><I>XX</I> </DT>
<DD>Send raw FTP command <I>XX</I> after each file transferred.</DD>

<DT><B>-Y </B><I>XX</I> </DT>
<DD>
Send raw FTP command <I>XX</I> before logging out.
<P>
The <B>-W</B>, <B>-X</B>, and <B>-Y</B> options are useful for advanced
users  who need to tweak behavior on some servers.
For example, users accessing mainframes might need
to  send  some special SITE commands to set blocksize
and record format information.
<P>
For these options, you can use them multiple times
each if you need to send multiple commands.
For the
<B>-X</B> option, you can use the  cookie <TT>%s</TT>  to  expand
into the name of the file that was transferred.
</DD>

<DT><B>-o </B><I>XX</I> </DT>
<DD>Set advanced option <I>XX</I>.
<P>
This option is used primarily for debugging.
It sets the value of an internal variable to an integer value.
An example usage would be:
<tt>-o useFEAT=0,useCLNT=1</tt>
which in this case, disables use of the
FEAT command and enables use of the CLNT command.
The available variables include:
<tt>usePASV</tt>,
<tt>useSIZE</tt>,
<tt>useMDTM</tt>,
<tt>useREST</tt>,
<tt>useNLST_a</tt>,
<tt>useNLST_d</tt>,
<tt>useFEAT</tt>,
<tt>useMLSD</tt>,
<tt>useMLST</tt>,
<tt>useCLNT</tt>,
<tt>useHELP_SITE</tt>,
<tt>useSITE_UTIME</tt>,
<tt>STATfileParamWorks</tt>,
<tt>NLSTfileParamWorks</tt>,
<tt>require20</tt>,
<tt>allowProxyForPORT</tt>,
<tt>doNotGetStartCWD</tt>.
</DD>

</blockquote>

<H2>Description</H2>
 <P>
The purpose of <I>ncftpls</I> is to do remote directory listings
using the File Transfer Protocol without entering an interactive shell.
This lets you write shell scripts or other unattended processes that can
do FTP. <P>
The default behavior is to print the directory listing in columnized
format (i.e. ls&nbsp;-CF), but that is not very useful for scripting. This example
uses the <B>-1</B> flag, to print one file per line: <blockquote>
<pre>$ ncftpls -1 ftp://ftp.ncftp.com/ncftp/</pre>
 </blockquote>

<P>Better yet, try the machine readable format:
<blockquote>
<pre>$ ncftpls -m ftp://ftp.ncftp.com/ncftp/
type=cdir;modify=20050407005654;UNIX.mode=0755 /ncftp
type=pdir;modify=20010521005346;UNIX.mode=0755 /
type=dir;modify=20050512221217;UNIX.mode=0755 binaries
type=file;size=95832;modify=19971122045900;UNIX.mode=0644 ncftp-1.9.5.tar.gz
type=file;size=192937;modify=19980320033600;UNIX.mode=0644 ncftp-2.4.3.tar.gz
type=file;size=409722;modify=20050325011837;UNIX.mode=0644 ncftp-3.1.9-src.tar.bz2
type=file;size=516060;modify=20050325011837;UNIX.mode=0644 ncftp-3.1.9-src.tar.gz
type=file;size=655834;modify=20050325011837;UNIX.mode=0644 ncftp-3.1.9-src.zip</pre>
</blockquote>
<P>Regrettably, many servers won't work with the machine redable option,
since they don't support the required FTP server software extensions (MLSD)
that make this possible.
Also beware that the fields shown may vary, as well as the order.
See the official machine readable list format <a href="http://www.ncftp.com/ncftp/doc/draft-ietf-ftpext-mlst-16.txt">documentation</a> for details.

<P>
You can also do a remote "ls&nbsp;-l",
by using <tt>ncftpls&nbsp;-l</tt>. If you want to try other flags (but be careful, the remote server may not support them), you have to use them
with the <B>-x</B> flag. For example, if you wanted to do a remote "ls&nbsp;-lrt", you
could do this:
<blockquote>
<pre>$ ncftpls -x &quot;-lrt&quot; ftp://ftp.ncftp.com/ncftp/</pre>
</blockquote>

<P>If you wanted to filter the listing, say, to show just files that ended
in the extension <TT>.TXT</TT>, you could try the <B>-i</B> flag, like this:
<blockquote>
<pre>$ ncftpls -1 -i '*.TXT' ftp://ftp.freebsd.org/pub/FreeBSD/</pre>
</blockquote>

<P>Filtering may not work, since it depends on the FTP server software
implementation.  Here's a better way which does not depend on the server:
<blockquote>
<pre>$ ncftpls -1 ftp://ftp.freebsd.org/pub/FreeBSD/ | grep -i '\.TXT$' </pre>
</blockquote>

<P>
By default the program tries
to open the remote host and login anonymously, but you can specify a username
and password information like you can with <I>ncftpget</I> or <I>ncftpput</I>.  

<P>
Note that the standard specifies that URL pathnames are are relative pathnames.
For FTP, this means that URLs specify relative pathnames from the start
directory, which for user logins, are typically the user's home directory.
If you want to use absolute pathnames, you need to include a literal slash,
using the "%2F" code for a "/" character.  Examples: <blockquote>
<pre>$ ncftpls -u linus ftp://ftp.kernel.org/%2Fusr/src/
$ ncftpls ftp://steve@ftp.apple.com/%2Fetc/</pre>
</blockquote>




<H2>Diagnostics</H2>

<blockquote>

<P>
<I>ncftpls</I> returns the following exit values: 
<OL start="0">
<LI>Success. </LI><LI>Could not connect to
remote host. </LI><LI>Could not connect to remote host - timed out. </LI><LI>Transfer failed.
</LI><LI>Transfer failed - timed out. </LI><LI>Directory change failed. </LI><LI>Directory change failed
- timed out. </LI><LI>Malformed URL. </LI><LI>Usage error. </LI><LI>Error in login configuration file.
</LI><LI>Library initialization failed. </LI><LI>Session initialization failed.  </LI>
</OL>

</blockquote>

<H2>Author</H2>
<blockquote>
 <P>
Mike Gleason, <a href="http://www.ncftp.com">NcFTP Software</a>.
</blockquote>
<H2>See Also</H2>
<blockquote>
 <P>
<I><I>ncftpput</I>(1)</I>, <I><I>ncftpget(1)</I>,</I>
<I><I>ncftp</I>(1)</I>, <I><I>ftp</I>(1)</I>, <I><I>rcp</I>(1)</I>, <I><I>tftp</I>(1)</I>. <P>
<I>LibNcFTP</I>  (<a href="http://www.ncftp.com/libncftp/">http://www.ncftp.com/libncftp/</a>).
</blockquote>
</BODY></HTML>
